Split title/description/details and use base-R macros for package Rd#11
Conversation
Parser (R/tags.R):
- Pre-tag content now splits across blank lines into title (para 1),
description (para 2), details (para 3+), matching roxygen2 behavior.
Previously everything past the first blank line was jammed into description.
- Paragraph breaks inside details are preserved as paragraph separators.
- Drop a trailing empty details state when no content followed the blank line
(e.g., a stray '#'' before '@param').
Package Rd generator (R/rd.R):
- Switch generate_package_rd to base-R Rd macros: \packageTitle{},
\packageDescription{}, \packageAuthor{}, \packageMaintainer{}, and
\packageIndices{}. DESCRIPTION is the source of truth.
- Hand-written paragraphs (now correctly parsed as details) land in \details{}.
- Drop the bespoke maintainer-from-DESCRIPTION helper - macros do this at
help-render time.
Tested against eddelbuettel/rspdlite: man/formatter.Rd is byte-identical to
roxygen2's output except for the header comment; man/rspdlite-package.Rd
now correctly populates \details{} (was missing before) and delegates
title/description/author to DESCRIPTION via macros.
I was sufficiently unclear, my bad. I ran my |
|
There's a real UX question buried in this: default behavior of
Neither is in scope for this PR. Just worth flagging. |
|
Agree completely--it's an open question without a perfect answer. Maybe even a defensive posture is good: do not overwrite a |
2 participants
Summary
\details{}never got populated.generate_package_rd()uses base-R Rd macros (\packageTitle{},\packageDescription{},\packageAuthor{},\packageMaintainer{},\packageIndices{}) instead of baking content into the Rd file. DESCRIPTION is the source of truth._PACKAGEblock's description now land in\details{}— the slot for design notes, limitations, etc.get_maintainer_from_desc()helper.Triggered by Dirk Eddelbuettel's review of tinyrox 0.3.3 against
rspdlite.Test plan
tinyrox::document(); tinypkgr::install(); tinytest::test_package('tinyrox')cleaneddelbuettel/rspdlite:man/formatter.Rdis byte-identical to roxygen2's output except for the header comment;man/rspdlite-package.Rdcorrectly populates\details{}(was missing) and uses macros for title/description/authortools::checkRd()on the regeneratedrspdlite-package.Rdreturns cleancorteza(an unrelated downstream): no empty\details{}blocks after fresh installVisible behavior change
For packages with a
_PACKAGEblock, the generatedpkg-package.Rdswitches from hardcoded title/description/author to macro-based delegation to DESCRIPTION. Same content if R-file and DESCRIPTION agree; different if they diverge. Also adds a "Package Content" function index (was missing).Out of scope (separate follow-ups)
##'(legacy two-hash) doc prefix isn't recognized —R/parse.R:17only matches^#'. Surfaced because rspdlite'sR/wrap.Ruses this style.namespace = "append"mode that wasn't reproducible against rspdlite (it has no@export/@importtags). Needs a different repro.